velo

Plot velocity vectors, crosses, anisotropy bars and wedges

Synopsis

velo(cmd0::String="", arg1=nothing; kwargs...)

Reads data values from files or direct inputs and plots geodesy symbols on a map. You may choose from velocity vectors and their uncertainties, rotational wedges and their uncertainties, anisotropy bars, or strain crosses. Symbol fills or their outlines may be colored based on constant parameters or via color lookup tables.

You can make four different geodetic symbols: Rotational wedges, velocity error ellipses with vector, anisotropy bars, and strain crosses. The first two symbols allow you to select separate colors and pens for the main symbol and its error component.

Required Arguments

Data Input

• Table data: Provide data as a file name, a GMTdataset, a matrix, or any tabular data format.

• J or proj or projection : – proj=
  Select map projection. More at [proj](../common_opts/opt_J.html)

• R or region or limits : – limits=(xmin, xmax, ymin, ymax) | limits=(BB=(xmin, xmax, ymin, ymax),) | limits=(LLUR=(xmin, xmax, ymin, ymax),units=“unit”) | …more
  Specify the region of interest. More at [limits](../common_opts/opt_R.html). For perspective view view, optionally add zmin,zmax. This option may be used to indicate the range used for the 3-D axes. You may ask for a larger w/e/s/n region to have more room between the image and the axes.

S?

Selects the meaning of the columns in the data file and the figure to be plotted. In all cases, the scales are in data units per length unit and sizes are in length units (default length unit is controlled by `PROJ_LENGTH_UNIT` unless **c**, **i**, or **p** is appended).

• Se or velo_NE : – *velo_NE=[velscale/]confidence[+ffont]“ : Velocity ellipses in (N,E) convention**

  The `velscale` sets the scaling of the velocity arrows. If velscale is not given then we read it from the data file as an extra column. The `confidence` sets the 2-dimensional confidence limit for the ellipse, e.g., 0.95 for 95% confidence ellipse. Use **+f** to set the font and size of the text [9p,Helvetica,black]; give **+f0** to deactivate labeling. The arrow will be drawn with the pen attributes specified by the **W** option and arrow-head can be colored via **fill**. The ellipse will be filled with the color or shade specified by the **uncertaintyfill** option [default is transparent], and its outline will be drawn if **L** is selected using the pen selected (by **W** if not given by **L**). 
  
  Note: If confidence is nonzero and neither **L** nor **E** are set then we use **W** (or default) to draw ellipse outlines. 
  
  Parameters are expected to be in the following columns:
  - 1,2: longitude, latitude of station (`yx` option interchanges order)
  - 3,4: eastward, northward velocity (`yx` option interchanges order)
  - 5,6: uncertainty of eastward, northward velocities (1-sigma) (`yx` option interchanges order)
  - 7: correlation between eastward and northward components
  - Trailing text: name of station (optional).

• Sn or aniso : – aniso=true | aniso=barscale Anisotropy bars

  The barscale sets the scaling of the bars. If barscale is not given then we read it from the data file as an extra column. Unless arrow is used to change it via modifier +hshape, the vector shape defaults to 0.1.

  Parameters are expected to be in the following columns:

  • 1,2: longitude, latitude of station (yx option interchanges order)
  • 3,4: eastward, northward components of anisotropy vector (yx option interchanges order)

• Sr or velo_rotated : – *velo_rotated=[velscale/]confidence[+ffont]“ : Velocity ellipses in rotated convention**

  The velscale sets the scaling of the velocity arrows. If velscale is not given then we read it from the data file as an extra column. The confidence sets the 2-dimensional confidence limit for the ellipse, e.g., 0.95 for 95% confidence ellipse. Use +f to set the font and size of the text [9p,Helvetica,black]; give +f0 to deactivate labeling. The arrow will be drawn with the pen attributes specified by the W option and arrow-head can be colored via fill. The ellipse will be filled with the color or shade specified by the uncertaintyfill option [default is transparent], and its outline will be drawn if L is selected using the pen selected (by W if not given by L).

  Note: If confidence is nonzero and neither L nor E are set then we use W (or default) to draw ellipse outlines.

  Parameters are expected to be in the following columns:

  • 1,2: longitude, latitude, of station (yx option interchanges order)
  • 3,4: eastward, northward velocity (yx option interchanges order)
  • 5,6: semi-major, semi-minor axes
  • 7: counter-clockwise angle, in degrees, from horizontal axis to major axis of ellipse.
  • Trailing text: name of station (optional)

• Sw or wedges : – wedges=wedgemag | wedges=(wedgescale,wedgemag)
  

  The wedgescale sets the size of the wedges. If wedgescale is not given then we read it from the data file as an extra column. Rotation values are multiplied by wedgemag before plotting. For example, setting wedgemag to 1.e7 works well for rotations of the order of 100 nanoradians/yr. Use fill to set the fill color or shade for the wedge, and uncertaintyfill to set the color or shade for the uncertainty.

  Parameters are expected to be in the following columns:

  • 1,2: longitude, latitude, of station (yx option interchanges order)
  • 3: rotation in radians
  • 4: rotation uncertainty in radians

• Sx” or strain : – strain=cross_scale
  

  The cross_scale sets the size of the cross. If cross_scale is not given then we read it from the data file as an extra column.

  Parameters are expected to be in the following columns:

  • 1,2: longitude, latitude, of station (yx option interchanges order)
  • 3: eps1, the most extensional eigenvalue of strain tensor, with extension taken positive.
  • 4: eps2, the most compressional eigenvalue of strain tensor, with extension taken positive.
  • 5: azimuth of eps2 in degrees CW from North.

Optional Arguments

• A or arrow or arrows : – arrow=parameters
  Modify vector parameters. For vector heads, append vector head size [Default is 9p]. See Vector Attributes for specifying additional attributes.

• R or region or limits : – limits=(xmin, xmax, ymin, ymax) | limits=(BB=(xmin, xmax, ymin, ymax),) | limits=(LLUR=(xmin, xmax, ymin, ymax),units=“unit”) | …more
  Specify the region of interest. More at [limits](../common_opts/opt_R.html). For perspective view view, optionally add zmin,zmax. This option may be used to indicate the range used for the 3-D axes. You may ask for a larger w/e/s/n region to have more room between the image and the axes.

• C or color or cmap : – cmap=cpt
  Give a CPT and let symbol color normally set by G be determined from the magnitude. See Z for other selections.

• D or sigma_scale : – *sigma_scale=scale* Can be used to rescale the uncertainties of velocities (Se and Sr) and rotations (Sw).

• E or uncertaintyfill or fill_wedges : – uncertaintyfill=fill
  Sets the color or shade used for filling uncertainty wedges (Sw) or velocity error ellipses (Se or Sr). If E is not specified, the uncertainty regions will be transparent.

  Note: Using C and Z=“+e” will update the uncertainty fill color based on the selected measure in Z [magnitude error].

• G or fill : – fill=color
  Select color or pattern for filling of symbols [Default is no fill].

  Note: Using C (and optionally Z) will update the symbol fill color based on the selected measure in Z [magnitude].

• H or scale : – scale=true | scale=scale
  Scale symbol sizes and pen widths on a per-record basis using the scale read from the data file. The symbol size is either provided by convention or via the input size column. Alternatively, append a constant scale that should be used instead of reading a scale column.

• I or intens or intensity : – intens=val | intens=:a
  Use the supplied intens value (nominally in the ±1 range) to modulate the compressional fill color by simulating illumination [none]. If no intensity is provided we will instead read intens from an extra data column after the required input columns determined by convention.

L or outline : [pen[+c[f|l]]]

Draw lines. Ellipses and rotational wedges will have their outlines drawn using current pen (see **W**). Alternatively, append a separate pen to use for the error outlines. If the modifier **+cl** is appended then the color of the pen are updated from the CPT (see **C**). If instead modifier **+cf** is appended then the color from the cpt file is applied to error fill only [Default]. Use just **+c** to set both pen and fill color.

• N or no_clip or noclip : – no_clip=true
  Do not skip symbols that fall outside the frame boundary specified by region. [Default plots symbols inside frame only].

• U or time_stamp : – time_stamp=true | time_stamp=(just=“code”, pos=(dx,dy), label=“label”, com=true)
  Draw GMT time stamp logo on plot. More at [timestamp](../common_opts/opt_U.html)

• V or verbose : – verbose=true | verbose=level
  Select verbosity level. More at [verbose](../common_opts/opt_V.html)

W or pen : [pen][+c[f|l]]

Set pen attributes for velocity arrows, ellipse circumference and fault plane edges. [Defaults: width = 0.25p, color = black, style = solid]. If the modifier **+cl** is appended then the color of the pen are updated from the CPT (see **C**). If instead modifier **+cf** is appended then the color from the cpt file is applied to symbol fill only [Default]. Use just **+c** to set both pen and fill color.

• X or xshift or x_offset : xshift=true | xshift=x-shift | xshift=(shift=x-shift, mov=“a|c|f|r”)
  Shift plot origin. More at [xshift](../common_opts/opt_X.html)

• Y or yshift or y_offset : yshift=true | yshift=y-shift | yshift=(shift=y-shift, mov=“a|c|f|r”)
  Shift plot origin. More at [yshift](../common_opts/opt_Y.html)

Z or colorbar_quantity : [m|e|n|u][+e]

Select the quantity that will be used with the CPT given via **C** to set the fill color. Choose from:
- **m**: magnitude (vector magnitude or rotation magnitude)
- **e**: east-west velocity
- **n**: north-south velocity
- **u**: user-supplied data column (supplied after the required columns)

To instead use the corresponding error estimates (i.e., vector or rotation uncertainty) to lookup the color and paint the error ellipse or wedge instead, append **+e**.

• bi or binary_in : – binary_in=??
  Select native binary format for primary table input. More at

• di or nodata_in : – nodata_in=??
  Substitute specific values with NaN. More at

• e or pattern : – pattern=??
  Only accept ASCII data records that contain the specified pattern. More at

• f or colinfo : – colinfo=??
  Specify the data types of input and/or output columns (time or geographical data). More at

• g or gap : – gap=??
  Examine the spacing between consecutive data points in order to impose breaks in the line. More at

• h or header : – header=??
  Specify that input and/or output file(s) have n header records. More at

• i or incol or incols : – incol=col_num | incol=“opts”
  Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only). More at incol

• p or view or perspective : – view=(azim, elev)
  Default is viewpoint from an azimuth of 200 and elevation of 30 degrees.
  Specify the viewpoint in terms of azimuth and elevation. The azimuth is the horizontal rotation about the z-axis as measured in degrees from the positive y-axis. That is, from North. This option is not yet fully expanded. Current alternatives are:

  • view=??
    A full GMT compact string with the full set of options.
  • view=(azim,elev)
    A two elements tuple with azimuth and elevation
  • view=true
    To propagate the viewpoint used in a previous module (makes sense only in bar3!) More at [perspective](../common_opts/opt_p.html)

• q or inrows : – inrows=??
  Select specific data rows to be read and/or written. More at

• t or transparency or alpha: – alpha=50
  Set PDF transparency level for an overlay, in (0-100] percent range. [Default is 0, i.e., opaque]. Works only for the PDF and PNG formats.

• yx : – yx=true
  Swap 1st and 2nd column on input and/or output. More at

Vector Attributes

Vector attributes are controlled by options and modifiers. All vectors require you to specify the begin point (x_b, y_b) and the end point (x_e, y_e), or alternatively the direction d and length L, while for map projections we usually specify the azimuth α instead.

Several modifiers may be appended to vector-producing options for specifying the placement of vector heads, their shapes, and the justification of the vector. Below, left and right refers to the side of the vector line when viewed from the beginning point (b) to the end point (e) of a line segment:

• +a : Append argument to set the angle θ of the vector head apex [30].

• +b : Place a vector head at the beginning of the vector path [none]. Optionally, append t for a terminal line, c for a circle, s for a square, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Note: For geovectors only a and A are available. Further append l|r to only draw the left or right half-sides of this head [both sides].

• +c : Select the vector data quantity magnitude for use with CPT color look-up [Default requires a separate data column following the 2 or 3 coordinates]. Requires that data quantity scaling (with unit q via +v or +z) and a CPT have been selected.

• +e : Place a vector head at the end of the vector path [none]. Optionally, append t for a terminal line, c for a circle, s for a square, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Note: For geovectors only a and A are available. Further append l|r to only draw the left or right half-sides of this head [both sides].

• +g : Append [fill] sets the vector head fill [Default fill is used, which may be no fill]. Turn off vector head fill by not appending a fill. Some modules have a separate -G option and if used will select the fill as well.

• +h : Append shape of the vector head (range -2/2). Default is controlled by MAP_VECTOR_SHAPE [default is theme dependent]. A zero value produces no notch. Positive values moves the notch toward the head apex while a negative value moves it away.

• +m : Places a vector head at the mid-point the vector path [none]. Append f or r for forward or reverse direction of the vector [forward]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides]. Cannot be combined with +b or +e.

• +n : Give [norm[/min]] to scale down vector attributes (pen thickness, head size) with decreasing length, where vector plot lengths shorter than norm will have their attributes scaled by length/norm [other arrow attributes remain invariant to length]. Optionally, append /min for the minimum shrink factor (in the 0-1 range) that we will shrink to [0.25]. For Cartesian vectors, please specify a norm in plot units, while for geovectors specify a norm in map units (see Distance units) [k]. Alternatively, append unit q to indicate we should use user quantity units in making the decision; this means the user also must select user quantity input via +v or +z. If no argument is given then +n ensures vector heads are not shrunk and always plotted regardless of vector length [Vector heads are not plotted if exceeding vector length].

• +o : Specify the oblique pole [plon/plat] for the great or small circles. Only needed for great circles if +q is given. If no pole is appended then we default to the north pole. Input arguments are then lon lat arclength with the latter in map distance units; see +q of angular limits instead.

• +p : Sets the vector pen attributes [pen]. If no pen is appended then the head outline is not drawn. [Default pen is half the width of stem pen, and head outline is drawn]. The vector stem attributes are controlled by -W.

• +q : Means the input direction, length data instead represent the start and stop opening angles of the arc segment relative to the given point. See +o to specify a specific pole for the arc [north pole].

• +t : [b|e]trim - Shift the beginning or end point (or both) along the vector segment by the given trim; append suitable unit (c, i, or p). If the modifiers b|e are not used then trim may be two values separated by a slash, which is used to specify different trims for the beginning and end. Positive trims will shorted the vector while negative trims will lengthen it [no trim].

In addition, all but circular vectors may take these modifiers:

• +j : The just determines how the input x,y point relates to the vector. Choose from beginning [default], end, or center.

• +s : The input angle, length are instead the (x_e, y_e) coordinates of the vector end point.

Finally, Cartesian vectors and geovectors may take these modifiers (except in grdvector) which can be used to convert vector components to polar form or magnify user quantity magnitudes into plot lengths:

• +v : [i|l]scale - Expects a scale to magnify the polar length in the given unit. If i is prepended we use the inverse scale while if l is prepended then it is taken as a fixed length to override input lengths. Append unit q if input magnitudes are given in user quantity units and we will scale them to current plot unit for Cartesian vectors (see PROJ_LENGTH_UNIT for how to change the plot unit) or to km for geovectors. In addition, if +c is selected then the vector magnitudes may be used for CPT color-lookup (and no extra data column is required by -C).

• +z : [scale] - Expects input Δx, Δy vector components and uses the scale [1] to convert to polar coordinates with length in given unit. Append unit q if input components are given in user quantity units and we will scale to current plot unit for Cartesian vectors (see PROJ_LENGTH_UNIT for how to change the plot unit) or to km for geovectors. In addition, if +c is selected then the vector magnitudes may be used for CPT color-lookup (and no extra data column is required by -C).

Note: Vectors were completely redesigned for GMT5 which separated the vector head (a polygon) from the vector stem (a line). In GMT4, the entire vector was a polygon and it could only be a straight Cartesian vector. Yes, the old GMT4 vector shape remains accessible if you specify a vector (-Sv|V) using the GMT4 syntax, explained here: size, if present, will be interpreted as tailwidth/headlength/halfheadwidth [Default is 0.075c/0.3c/0.25c (or 0.03i/0.12i/0.1i)]. By default, arrow attributes remain invariant to the length of the arrow. To have the size of the vector scale down with decreasing size, append +nnorm, where vectors shorter than norm will have their attributes scaled by length/norm. To center the vector on the balance point, use -Svb; to align point with the vector head, use -Svh; to align point with the vector tail, use -Svt [Default]. To give the head point’s coordinates instead of direction and length, use -Svs. Upper case B, H, T, S will draw a double-headed vector [Default is single head]. Note: If headlength/halfheadwidth are given as 0/0 then only the head-less vector stick will be plotted.

A GMT 4 vector has no separate pen for the stem – it is all part of a Cartesian polygon. You may optionally fill and draw its outline. The modifiers listed above generally do not apply. Note: While the tailwidth and headlength parameters are given as indicated, the halfheadwidth is oddly given as the half-width in GMT 4 so we retain that convention here (but have updated the documentation).

Data Column Order

The S option determines how many data columns are required to generate the selected symbol. In addition, your use of options H, I and t will require extra columns, as will a S option without the size or a user-column selected via -Zu for color lookup purposes. The order of the data record is fixed regardless of option order, even if not all items may be activated.

We expect data columns to come in the following order:

lon lat symbol-columns [usercol] [size] [scale] [intens] [transp [transp2]] [trailing-text]

where symbol-columns represent the normally required data columns, and items given in brackets are optional and under the control of the stated options (the trailing text is always optional). Note: You can use -i to rearrange your data record to match the expected format.

Examples

The following should make big red arrows with green ellipses, outlined in red. Note that the 39% confidence scaling will give an ellipse which fits inside a rectangle of dimension Esig by Nsig:

velo("""
0. -8. 0.0 0.0 4.0 6.0 0.500 4x6
-8. 5. 3.0 3.0 0.0 0.0 0.500 3x3
0. 0. 4.0 6.0 4.0 6.0 0.500
-5. -5. 6.0 4.0 6.0 4.0 0.500 6x4
5. 0. -6.0 4.0 6.0 4.0 -0.500 -6x4
0. -5. 6.0 -4.0 6.0 4.0 -0.500 6x-4
""", region=(-10,10,-10,10), pen=(0.6,:red), error_fill=:green, outline=true,
    symbol="e0.2/0.39/18", frame=(axes=:auto, grid=1), proj=:linear, figscale=(0.4,0.4),
    arrow="0.3c+p1p+e+gred", show=true)

This example should plot some residual rates of rotation in the Western Transverse Ranges, California. The wedges will be dark gray, with light gray wedges to represent the 2-sigma uncertainties:

velo("""
241.4806 34.2073 5.65E-08 1.17E-08
241.6024 34.4468 -4.85E-08 1.85E-08
241.0952 34.4079 4.46E-09 3.07E-08
241.2542 34.2581 1.28E-07 1.59E-08
242.0593 34.0773 -6.62E-08 1.74E-08
241.0553 34.5369 -2.38E-07 4.27E-08
241.1993 33.1894 -2.99E-10 7.64E-09
241.1084 34.2565 2.17E-08 3.53E-08
""", symbol="w0.4i/1.e7", pen=0.75, fill=:darkgray, error_fill=:lightgray,
    scale_down=2, proj=:merc, figscale="2.2i",
    region=(240,243,32.5,34.75), frame=(axes=:auto, annot=:auto),
    show=true)

Notes

This module provides specialized plotting capabilities for geodetic data including GPS velocity vectors, rotational deformation, anisotropy measurements, and strain tensor visualizations. The error representation (ellipses or wedges) can be customized independently from the main symbol to properly represent measurement uncertainties.

For velocity ellipses, the confidence parameter controls the size of the uncertainty ellipse according to the desired confidence level (e.g., 0.39 for 1-sigma, 0.95 for 95% confidence). The correlation coefficient between eastward and northward components is critical for proper ellipse orientation.

References

Kurt L. Feigl, Department of Geology and Geophysics at University of Wisconsin-Madison, Madison, Wisconsin, USA

See Also

plot, arrows, meca, coupe